REQUEST_COMPLETE_HANDLER callback function

Article
06/19/2017

Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

The ProtocolRequestComplete function is a required driver function. This function completes the processing of a protocol-initiated query or set for which NdisRequest returned NDIS_STATUS_PENDING.

A connection-oriented protocol that calls NdisCoRequest but never NdisRequest must have a fully functional ProtocolCoRequestComplete function, rather than a ProtocolRequestComplete function.

Syntax

REQUEST_COMPLETE_HANDLER ProtocolRequestComplete;

VOID ProtocolRequestComplete(
  _In_ NDIS_HANDLE   ProtocolBindingContext,
  _In_ PNDIS_REQUEST NdisRequest,
  _In_ NDIS_STATUS   Status
)
{ ... }

Parameters

ProtocolBindingContext [in]
Specifies the handle to a protocol-allocated context area in which the protocol driver maintains per-binding run-time state. The driver supplied this handle when it called NdisOpenAdapter.
NdisRequest [in]
Pointer to the protocol-supplied structure previously passed to NdisRequest.
Status [in]
Specifies the final status of the request set by the underlying driver or by NDIS. This argument determines what ProtocolRequestComplete does with the information at NdisRequest.

Return value

None

Remarks

ProtocolRequestComplete uses the input Status as follows:

If this argument is NDIS_STATUS_SUCCESS, the BytesRead or BytesWritten member of the NDIS_REQUEST structure has been set by NDIS or the underlying driver to specify how much protocol-supplied information was transferred from the buffer at InformationBuffer to the NIC in a set operation or how much information was returned at InformationBuffer in response to a query operation.

If the protocol made a query, ProtocolRequestComplete can use the data returned at InformationBuffer in any protocol-determined way, depending on the value of the Oid member.

For example, if the protocol originally initiated an OID_GEN_MAXIMUM_SEND_PACKETS query, ProtocolRequestComplete might set up state variables in the ProtocolBindingContext area to throttle the number of outstanding sends the driver will set up for subsequent calls to NdisSendPackets.
If this argument is NDIS_STATUS_INVALID_LENGTH or NDIS_STATUS_BUFFER_TOO_SHORT, the BytesNeeded member specifies the Oid-specific value of the InformationBufferLength member required to carry out the requested operation.

In these circumstances, ProtocolRequestComplete can allocate sufficient buffer space for the request, set up another NDIS_REQUEST structure with the required InformationBufferLength and same Oid, and retry the call to NdisRequest.

ProtocolRequestComplete can retry requests for certain other NDIS_STATUS_XXX arguments, as well, as described in the reference for NdisRequest.
If this argument is an NDIS_STATUS_XXX that is an unrecoverable error, ProtocolRequestComplete should release the memory allocated for the NDIS_REQUEST structure and determine whether the driver should call NdisReset, close the binding, or adjust its binding-specific state information to handle continued network I/O operations on the binding.

For global queries and sets, the underlying connectionless miniport driver's call to NdisMQueryInformationComplete or NdisMSetInformationComplete causes NDIS to call the ProtocolRequestComplete function. NDIS forwards the miniport driver-determined Status passed to NdisM..InformationComplete as the input Status to ProtocolRequestComplete.

For binding-specific queries, NDIS calls the ProtocolRequestComplete function itself. Because the NDIS library maintains bindings for all miniport drivers, NDIS can return binding-specific information only about underlying drivers that report their medium-type as one for which the system provides a filter library. NDIS returns NDIS_STATUS_NOT_SUPPORTED for protocol-initiated binding-specific queries to other miniport drivers.

For more information about system-defined OIDs, see NDIS Object Identifiers.

ProtocolRequestComplete can be called before the protocol has had time to inspect the status code that NdisRequest returns at Status.

Requirements

Target platform	Desktop
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Use ProtocolOidRequestCompleteinstead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP
Header	Ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL